home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / langs / gemfst18.lzh / GEMFINST.DOC < prev    next >
Encoding:
Text File  |  1992-12-06  |  14.6 KB  |  595 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                                     GemFast v1.8
  29.  
  30.                         Public Domain GEM Programming Library
  31.                                     By Ian Lepore
  32.          
  33.         
  34.                          Installation and Portability Notes
  35.         
  36.         
  37.         
  38.         
  39.         
  40.         
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.        Contents
  72.  
  73.        Packing List  . . . . . . . . . . . . . . . . . . . . . . . . .  - 1 -
  74.  
  75.        Installation and Usage Instructions . . . . . . . . . . . . . .  - 2 -
  76.           Basic installation . . . . . . . . . . . . . . . . . . . . .  - 2 -
  77.           LD.TTP Installation (for HSC users)  . . . . . . . . . . . .  - 3 -
  78.           Usage  . . . . . . . . . . . . . . . . . . . . . . . . . . .  - 3 -
  79.           IMPORTANT RECOMPILE WARNING! . . . . . . . . . . . . . . . .  - 3 -
  80.  
  81.        GemFast System Overview . . . . . . . . . . . . . . . . . . . .  - 5 -
  82.           The GEMFAST.H header file  . . . . . . . . . . . . . . . . .  - 5 -
  83.           The AESFAST.A library  . . . . . . . . . . . . . . . . . . .  - 5 -
  84.           The VDIFAST.A library  . . . . . . . . . . . . . . . . . . .  - 5 -
  85.           Stack and memory usage . . . . . . . . . . . . . . . . . . .  - 6 -
  86.           GEM and supervisor mode  . . . . . . . . . . . . . . . . . .  - 6 -
  87.  
  88.        Portability Notes . . . . . . . . . . . . . . . . . . . . . . .  - 7 -
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                         - i -
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.        Packing List
  138.  
  139.  
  140.             GemFast v1.8 is distributed in 3 archive files, as follows:
  141.  
  142.                  GEMFST18.LZH -  Libraries, headers, and documentation.
  143.                  GEMFSC18.LZH -  Library source code.
  144.                  GEMFXM18.LZH -  Example application source code.
  145.  
  146.             The GEMFST18.LZH archive contains the following files:
  147.  
  148.                  AESFAST.A    -  The AES library.
  149.                  VDIFAST.A    -  The VDI library.
  150.                  GEMFAST.H    -  GEM programming header file.
  151.                  EXTERROR.H   -  Extended error message header file.
  152.                  GEMFAST.DOC  -  The library reference manual.
  153.                  GEMFINST.DOC -  This document.
  154.                  AESVRSN.DOC  -  Revision history for AES library.
  155.                  VDIVRSN.DOC  -  Revision history for VDI library.
  156.                  LD.TTP       -  New linker, required for HSC users.
  157.  
  158.             The GEMFSC18.LZH archive contains two other archives, which in
  159.             turn contain many files.  (It compresses much tighter this way.)
  160.             When unpacked, the following directory structure emerges:
  161.  
  162.                  VDIBIND\     -  All VDI library functions.
  163.                  AESBIND\     -  Low-level AES bindings.
  164.                  AESXBIND.S\  -  Extended bindings (ASM code).
  165.                  AESXBIND.C\  -  Extended bindings (C code).
  166.                  AESUTIL.S\   -  Low-level utilities (ASM code).
  167.                  AESUTIL.C\   -  Low-level utilities (C code).
  168.                  AESFUNCS\    -  The bulk of the high-level code.
  169.                  INCLUDE\     -  Header files.
  170.  
  171.             The GEMFXM18.LZH archive contains the following files:
  172.  
  173.                  (need a list here)
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                         - 1 -
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.        Installation and Usage Instructions
  204.  
  205.  
  206.             These installation instructions assume you are using GemFast with
  207.             a DRI-compatible compiler, and are using GemFast as your primary
  208.             GEM bindings system.  Compatible compilers are:
  209.  
  210.                  Sozobon C v1.x and v2.0
  211.                  Heat and Serve C (HSC) v1.34 or higher
  212.                  Laser / MegaMax C
  213.                  Alcyon C
  214.  
  215.             The distributed libraries are NOT compatible with other
  216.             compilers.  If your compiler is not on the above list, please
  217.             proceed to the Portability Notes chapter.
  218.  
  219.  
  220.        Basic installation
  221.  
  222.  
  223.             Installation of GemFast is fairly simple.  Copy the VDIFAST.A and
  224.             AESFAST.A files to the directory your compiler uses for
  225.             libraries.  If you use ALN or another indexed linker, be sure to
  226.             run DOINDEX to build new library index files.  Copy the GEMFAST.H
  227.             and EXTERROR.H files to the directory your compiler uses for
  228.             header files.  Put the documentation wherever you want.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                         - 2 -
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.        LD.TTP Installation (for HSC users)
  270.  
  271.  
  272.             If you're using Heat-and-Serve C v1.3x, you need to copy LD.TTP
  273.             to replace your current version.  Older versions of LD had some
  274.             compiled-in limits on the number of object files in a library. 
  275.             There are now so many modules in the GemFast libraries that these
  276.             limits get exceeded.  The new LD has larger default limits, and
  277.             also some new command line options that let you increase the
  278.             limits for any given run.  The new command line options are:
  279.  
  280.                  -lo####     The number of object files referenced/used.
  281.                  -lm####     The number of object files skipped/unused.
  282.                  -ls####     The number of non-local symbols.
  283.  
  284.             The default limits are 300 used object modules, 400 unused
  285.             modules from libraries (modules skipped during multipass
  286.             processing), and 1000 non-local symbols.  To double these limits,
  287.             add the following to your LD command line:
  288.  
  289.                  -lo600 -lm800 -ls2000
  290.  
  291.             The numbers you specify must be between 1 and 32767 inclusive. 
  292.             The larger the numbers, the more memory is needed at runtime.
  293.  
  294.  
  295.        Usage
  296.  
  297.  
  298.             To link your programs with the GemFast libraries, just include
  299.             the library names on the linker command line.  Example:
  300.  
  301.                  cc myprog.c aesfast.a vdifast.a dlibs.a
  302.  
  303.             There is now a linker order dependancy!  Many of the new high-
  304.             level functions require VDI services, so you must now place
  305.             VDIFAST.A after AESFAST.A on your linker command line.  The
  306.             libraries are still internally sequenced so that your linker will
  307.             only need to make one pass of each library.  Also, some of the
  308.             new high-level dialogs require runtime library services such as
  309.             sprintf(), so it is best if the GemFast libraries appear before
  310.             your C runtime library.
  311.  
  312.             You can use any runtime startup module you want, when your
  313.             compiler/linker provide several startup modules.  Nothing in the
  314.             GemFast libraries relies on items in the startup files.
  315.  
  316.  
  317.        IMPORTANT RECOMPILE WARNING!
  318.  
  319.  
  320.             You MUST recompile all your existing GEM object modules as a part
  321.             of installing v1.8!  Because macros in GEMFAST.H remap some
  322.             standard GEM calls through new internal library routines, it is
  323.             imperative that all your GEM-related object code be recompiled
  324.             using the new GEMFAST.H header file before you link *anything*
  325.  
  326.                                         - 3 -
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.             with the new libraries.
  336.  
  337.             It is hard for me to overstate the importance of this. 
  338.             Everything will die horribly if you link an existing object
  339.             module containing GEM calls with the new libraries.
  340.  
  341.             Here's my suggestion:  Go look *everywhere* on all your
  342.             partitions or disks.  Nuke all object files that have even a
  343.             remote chance of containing a GEM call.  If you have your own
  344.             libraries that contain GEM calls, nuke the libraries.  Do all the
  345.             deletions at once, then go through and recompile things where
  346.             necessary.
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                         - 4 -
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.        GemFast System Overview
  402.  
  403.  
  404.             GemFast provides complete support for GEM programming.  It
  405.             provides the GEM support for the Sozobon and HSC public domain
  406.             compilers.  In addition, it replaces the existing GEM support for
  407.             the Laser, MegaMax, and Alcyon compilers.  The low-level bindings
  408.             and utilties are written in hand-coded assembler to provide
  409.             maximum speed and memory efficiency.  The higher level functions
  410.             in the AES library are written in C to provide portability to
  411.             other compilers.
  412.  
  413.  
  414.        The GEMFAST.H header file
  415.  
  416.  
  417.             The GEMFAST.H header file defines constants and datatypes
  418.             frequently used in GEM programming.  In addition, it contains
  419.             declarations for all functions which return a value other than an
  420.             int.
  421.  
  422.             This header file also contains macros which remap old utility
  423.             function names to the newer (supported) names, and macros which
  424.             route standard GEM calls such as graf_mouse() through new support
  425.             routines such as grf_mouse().  The remapping is done at a macro
  426.             level to provide compatibility with compilers not using the low-
  427.             level GemFast bindings.  This means that you MUST include
  428.             GEMFAST.H into every source code module that contains GEM
  429.             function calls.
  430.  
  431.             This header file replaces the OBDEFS.H and GEMDEFS.H files
  432.             delivered with other GEM support systems.
  433.  
  434.  
  435.        The AESFAST.A library
  436.  
  437.  
  438.             The AESFAST.A library contains the low-level bindings to standard
  439.             AES functions, low-level utilities such as rectangle
  440.             calculations, and the high-level library functions.  All standard
  441.             AES functions are supported, including fsel_exinput(), and other
  442.             functions Atari added to the AES in TOS 1.04.  (Special code in
  443.             the fsel_exinput() binding makes it work properly on all TOS
  444.             versions.)
  445.  
  446.             The GEMFAST.DOC file documents all functions in the AESFAST.A
  447.             library which are not standard AES functions.  (Refer to any
  448.             standard GEM reference manual for descriptions of the standard
  449.             AES functions.)
  450.  
  451.  
  452.        The VDIFAST.A library
  453.  
  454.  
  455.             The VDIFAST.A library contains low-level bindings to the standard
  456.             VDI functions.  It does not contain every VDI function documented
  457.  
  458.                                         - 5 -
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.             in standard GEM programming manuals, but it contains all the
  468.             important ones.  (A few rarely-used functions such as
  469.             v_cellarray() and polaroid palette driver functions are
  470.             misssing.)  It does not contain any GDOS or FSMGDOS functions. 
  471.             (I expect to get docs on GDOS soon, then I can add bindings for
  472.             them.)
  473.  
  474.  
  475.        Stack and memory usage
  476.  
  477.  
  478.             The low-level bindings use no data memory other than the global
  479.             variables documented in GEMFAST.DOC.  Most low-level bindings use
  480.             50 bytes or less of stack space.  A noteable exception is
  481.             v_gtext(), which uses 50 bytes plus two times the length of the
  482.             string you pass to it.
  483.  
  484.             The higher level functions in the AES library use more stack
  485.             space, but rarely more than a couple hundred bytes, and never
  486.             more than 1k.  (I've used the new dynamic dialogs with a 2k stack
  487.             without any problem.)
  488.  
  489.             The dynamic dialogs contain embedded resource data, and this has
  490.             bloated the AESFAST.A library (and will do the same to your
  491.             program) a bit.  Where possible, I've made similar functions
  492.             share internal data structures such as embedded resource data to
  493.             try to keep the total data size of your programs down to a
  494.             reasonable size.
  495.  
  496.  
  497.        GEM and supervisor mode
  498.  
  499.  
  500.             You cannot make AES calls from supervisor mode; it has to do with
  501.             the way the AES internals save registers.  With some herculean
  502.             efforts you can hack around it if you need to, but it'll require
  503.             custom assembler code on your part.
  504.  
  505.             You can make VDI calls from supervisor mode.
  506.  
  507.             If you use G_USERDEF objects, be aware that the custom drawing
  508.             routine you supply will be called in supervisor mode.  This means
  509.             that it cannot make AES calls.  Also, if you make DOS, BIOS, or
  510.             XBIOS calls from the custom drawing routine, you may get a
  511.             spurious stack overflow error message from your C runtime library
  512.             bindings (gemdos(), bios(), and xbios() functions), because being
  513.             on the supervisor stack will confuse any stack checking these
  514.             routines do.
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                         - 6 -
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.        Portability Notes
  534.  
  535.  
  536.             Starting with GemFast v1.8, all high-level library functions are
  537.             coded in C, and should be fairly portable to other compilers. 
  538.             I've yet to try porting the libraries, and I'd expect a few
  539.             problems on a compiler where sizeof(int) is 4 bytes.
  540.  
  541.             The extended bindings (evnx_multi(), etc) and the low-level
  542.             utilities (rc_intersect(), etc) exist in both C and assembler
  543.             source code form.  For use with MWC or another compiler that
  544.             doesn't use DRI-standard object modules, just compile the code in
  545.             the AESXBIND.C and AESUTIL.C directories with your C compiler,
  546.             and they will take the place of the assembler routines from
  547.             AESXBIND.S and AESUTIL.S.  The C functions won't be as small or
  548.             fast as the assembler versions, but they will let you port
  549.             programs written for GemFast to your compiler.
  550.  
  551.             I hope to expand on these portability notes in future releases,
  552.             as well as making whatever code changes are needed to increase
  553.             portability.  I welcome feedback from anyone who ports GemFast to
  554.             other compilers.
  555.  
  556.             Note added at a much later date:  I have now done a preliminary
  557.             port of GemFast to Lattice C 5.52.  The good news is that a
  558.             release of GemFast that is compatible with both ANSI and K&R
  559.             compilers is a real possibility in the near future.  The bad news
  560.             is that it may be a commercial product rather than freeware. 
  561.             However, if it does become a commercial product, I promise that
  562.             it will be very reasonably priced, and that if you've sent me a
  563.             donation on the current version, you will receive a discount on
  564.             the commercial version if you choose to upgrade.
  565.  
  566.             Ian Lepore
  567.             05/31/92 (updated 12/06/92)
  568.             BIX      ianl
  569.             Internet ilepore@nyx.cs.du.edu
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.                                         - 7 -
  591.  
  592.  
  593.  
  594.  
  595.